package org.tigr.htc.request;

/*
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

import java.io.IOException;
import java.util.Map;

import org.tigr.htc.cmd.Command;
import org.tigr.htc.cmd.TaskGroup;

/**
 * The <b>IProxyServer</b> class 
 */

public interface IProxyServer {
    /**
     * <code>submit</code> submit the request to the grid.  If the request is valid and
     * is accepted by the cluster a unique positive id will be returned.  If there is 
     * error or the request is rejected the id returned will be less then 1.
     *
     * @return a <code>long</code> a unique id assigned to the request
     * @exception IllegalAccessException if a request has already been submitted
     * @exception IOException if a network problem occurs
     */
    public long submit(HTCRequest p_request) 
	throws IllegalAccessException, IOException;

    /**
     * <code>waitForRequest</code> wait for the request to finish.
     *
     * @return a <code>long</code> id for the request that finished
     * @exception IllegalAccessException if request hasn't been submitted
     * @exception InterruptedException if interrupted while waiting
     */
    //    public long waitForRequest(HTCRequest p_request) 
    //	throws InterruptedException, IllegalAccessException;
    
    // not implemented yet
    //    public long waitForRequest(HTCRequest p_request, long p_millis) 
    //	throws InterruptedException, IllegalAccessException;
   
    /**
     * <code>stop</code> send a stop to the request.  This method doesn't
     * wait for the command to stop before it returns.
     *
     * @exception IOException if the request hasn't been submitted
     */
    public void stop(HTCRequest p_request) 
	throws IOException;

    /**
     *  <code>hold</code> send a hold/suspend command to a request. 
     * Delegated to proxy.
     *
     * @exception IOException if set is attempted after submission
     */
    public void hold(HTCRequest p_request) 
	throws IOException;

    /**
     * <code>resume</code> send a resume command to a request that has been
     * held/suspended by the user.  This will cause the request to 
     * be put back in a queue to be scheduled. This method doesn't
     * wait for the command to stop before it returns. 
     * Delegated to proxy.
     *
     * @exception IOException if set is attempted after submission
     */
    public void resume(HTCRequest p_request) 
	throws IOException;

    /**
     * <code>disconnect</code> client no longer wants event updates from server.
     * delegate to proxy server.
     *
     * @exception IOException if set is attempted after submission
     */
    public void disconnect(HTCRequest p_request) 
	throws IOException;


    /**
     * <code>getCommand</code> ask the server for the command that is 
     * associated with the id.  
     *
     * @param p_id a <code>long</code> id for an existing command
     * @return a <code>Command</code> the command object
     * @exception IOException if an network problem occurs
     */
    public Command getCommand(long p_id, HTCRequest p_request) 
	throws IOException;

    public boolean isNFS(String p_path) 
	throws IOException;

    /**
     * The method <code>getStatus</code> returns the status of the request specified as the
     * parameter. The resulting map contains two keys, 'ID' and 'state' that represent the state
     * of the request.
     * 
     * @param p_request
     * @return
     */
    public Map getStatus(HTCRequest p_request);
    
    /**
     * The method <code>getMonitorHost</code> returns the name of the HTCService host monitoring the
     * request.
     * 
     * @param p_request
     * 
     * @return <code>String</code> representing the host name, null if the monitor host cannot
     * be determined
     * 
     * @throws IOException
     */
    public String getMonitorHost(HTCRequest p_request) throws IOException;
    
    /**
     * The method <code>getTasks</code> returns the individual task information for array jobs. 
     * 
     * @return a <code>TaskGroup</code> representing the tasks associated with this array request
     * 
     * @throws IOException is an attempt is made to request tasks for non-array jobs
     */
    public TaskGroup getTasks (HTCRequest p_request) throws IOException;
    
    /**
     * The method <code>isLocal</code> returns the status of the proxy server. For local submissions this 
     * value is true and for remote submissions the value is false.
     *  
     * @return boolean true to indicate the server is performing local submits
     */
    public boolean isLocal();
    
    /**
     * The method <code>isPassEnvironment</code> provides the configuration for the proxy server
     * to pass the local environment to the grid jobs. This is read from a global configuration file.
     * 
     * @return a <code>boolean</code> of true if the environment is explicitly passed to the grid jobs
     * when the environment is not set by the user.
     */
    public boolean isPassEnvironment ();
}
